<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Attaching and Initialising the Interface
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot028.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot026.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot030.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc50">6.3</A>&nbsp;&nbsp;Attaching and Initialising the Interface</H2><UL>
<LI><A HREF="embroot029.html#toc23">A Note on Security</A>
</UL>

To use the interface, the Tcl program needs to be
attached to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> program. The attach request is initiated on the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, by calling the predicate
<A HREF="../bips/kernel/externals/remote_connect-3.html"><B>remote_connect/3</B></A><A NAME="@default119"></A> <SUP><A NAME="text5" HREF="embroot026.html#note5">2</A></SUP> from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. The Tcl program is then attached to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> program by executing the procedure <B>ec_remote_init</B><A NAME="@default122"></A> from Tcl. If no error
occurs, then the connection is established and the interface is set up.<BR>
<BR>
In more detail, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> predicate remote_connect/3 establishes a
socket listening for the connection from the Tcl side. It prints out, on
the stream <TT>log_output</TT>, the
hostname and the port number that the Tcl side should connect to:
<PRE CLASS="verbatim">
[eclipse 1]: remote_connect(Host/Port, Control, _InitGoal).
Socket created at address chicken.icparc.ic.ac.uk/25909
</PRE>
On the Tcl side, ec_remote_init is called with the hostname and port number
given by remote_connect/3:
<PRE CLASS="verbatim">
ec_remote_init chicken.icparc.ic.ac.uk 25909
</PRE>
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default123"></A><B>ec_remote_init <I>host port ?init_command? ?pass? ?format?</I></B><DD CLASS="dd-description"><BR>
	Initialise the remote Tcl interface on the Tcl side. A
	corresponding <B>remote_connect/3</B> must have been started on the
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, which specifies the hostname (<I>host</I>) and port
	number (<I>port</I>) to connect to. The optional <I>	init_command</I> is an is a Tcl command that will be invoked at the
	end of the attachment, before control is handed over to the
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side (see section&nbsp;<A HREF="embroot033.html#remote-control">6.7</A> for more
	details). <I>pass</I> and <I>format</I> are optional arguments for a simple
	security check: they specify an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term that will be
	matched against a corresponding term (using <A HREF="../bips/kernel/termcomp/EE-2.html"><B>==/2</B></A><A NAME="@default124"></A>) on the
	ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side before the connection is allow to proceed (<I>pass</I>
	will be sent to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side in EXDR format<SUP><A NAME="text6" HREF="embroot026.html#note6">3</A></SUP>; the default is
	an empty string, which is what <A HREF="../bips/kernel/externals/remote_connect_setup-3.html"><B>remote_connect_setup/3</B></A><A NAME="@default125"></A>
	expects).</DL>
If successful, some initial links are established between the two sides,
such as the control connection and the connection to allow rpc goals to be
sent from the Tcl to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. 
After the attachment, optional user-defined
initialisations are performed on both sides (via the InitGoal argument on
the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, and the init_command on the Tcl side), and the two
sides can then interact. Initially, the control is given to the Tcl side,
and <I>remote_connect/3</I> returns only when control is handed over to the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. <BR>
<BR>
As part of the attachment process, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> name of the control
connection is passed to the Tcl side. This can be accessed by the user
using the command:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default126"></A><B>ec_control_name</B><DD CLASS="dd-description"><BR>
returns the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> name of the control
connection. An error is raised if this procedure is called before
an attachment to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is made.
</DL>
Unimplemented functionality error will be raised if the Tcl or
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side are incompatible with each other. This can happen if
one side is outdated, e.g. if the remote Tcl interface used and the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
being connected to are not from the same version of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. In this
case, it is best to update both sides to the latest version of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>
<A NAME="toc23"></A>
<H3 CLASS="subsection"><A NAME="htoc51">6.3.1</A>&nbsp;&nbsp;A Note on Security</H3>
Once a Tcl side is attached to an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, the Tcl side can execute 
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> goals on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side via the <B>ec_rpc</B> mechanism. This 
may be a security concern as
this gives the Tcl side as much access to the resources on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side as the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process itself, even though the Tcl side can
potentially be anywhere reachable from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side via TCP.
However, the connection must be initiated from the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side, and the
attachment process must follow a protocol in order for a successful
attachment. Nevertheless,
if a third party somehow knew which Address to connect to, and follows the
protocol, it can `steal' the connection to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. No
authentication is performed by the simple <CODE>remote_connect_setup/3</CODE>,
but <A HREF="../bips/kernel/externals/remote_connect_accept-6.html"><B>remote_connect_accept/6</B></A><A NAME="@default127"></A> does allow a simple authentication
where it can require the Tcl side to send an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> term that matches
the one specified in calling the predicate. This is done before the Tcl
side is given the ability to run rpc goals on the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. <BR>
<BR>
It is also possible to limit the remote connection to the same machine as the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> process by specifying `localhost' as the host name in the
Host/Port address of <CODE>remote_connect/3</CODE>. The Tcl side must also
use `localhost' for the Host name in its client connection. <BR>
<BR>
Each peer queue is created by creating a new server socket on the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side and then accepting a client connection from the Tcl
side. The accept command is told where the client connection is from, and
the client host is checked against the client's host from the attachment,
to ensure that the same host has been connected. If not, the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
side will reject the particular connection. At this point, the security has
probably been compromised, and the two side should disconnect.<BR>
<BR>
Note also that by default, none of the information sent through the queues
between the remote side and the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side is encrypted. If the
programmer requires these communication channels to be secure, then such
encryptions need to be provided by the programmer.<BR>
<BR>
<HR>
<A HREF="embroot028.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot026.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot030.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
